import CodeBlock from "@theme/CodeBlock";
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

# @farmfe/js-plugin-sass
Support `sass` for Farm.

## Installation

<Tabs>
  <TabItem value="npm" label="npm">
    <CodeBlock>npm install @farmfe/js-plugin-sass sass</CodeBlock>
  </TabItem>
  <TabItem value="yarn" label="yarn">
    <CodeBlock>yarn add @farmfe/js-plugin-sass sass</CodeBlock>
  </TabItem>
  <TabItem value="pnpm" label="pnpm">
    <CodeBlock>pnpm add @farmfe/js-plugin-sass sass</CodeBlock>
  </TabItem>
</Tabs>

## Usage
```ts {2,6}
import { UserConfig } from '@farmfe/core';
import farmJsPluginSass from '@farmfe/js-plugin-sass';

const config: UserConfig = {
  plugins: [
    farmJsPluginSass({ /* options */ })
  ]
}
```

## Options
```ts
export type SassPluginOptions = {
  sassOptions?: StringOptions<'async'>;
  filters?: {
    resolvedPaths?: string[];
    moduleTypes?: string[];
  };

  /**
   * - relative or absolute path
   * - globals file will be added to the top of the sass file
   * - when file changed, the file can't be hot-reloaded
   *
   * relative to project root or cwd
   */
  implementation?: string | undefined;
  globals?: string[];
  additionalData?:
    | string
    | ((content?: string, resolvePath?: string) => string | Promise<string>);
};
```

### sassOptions
Sass options. See [sass options](https://sass-lang.com/documentation/js-api/interfaces/options/) for more details.

Example:
```ts
import path from 'node:path';
import { UserConfig } from '@farmfe/core';
import farmJsPluginSass from '@farmfe/js-plugin-sass';

const config: UserConfig = {
  plugins: [
    farmJsPluginSass({
      sassOptions: {
        loadPaths: [path.resolve(process.cwd(), 'styles')]
      }
    })
  ]
}

export default config;
```

### filters
Which files should be processed by `sass`. Default to `{ resolvedPaths: ['\\.(s[ac]ss)$'] }` for load and `{ moduleTypes: ['sass'] }` for transform.

* `resolvedPaths`: Only files under these paths will be processed. Support regex.
* `moduleTypes`: Only files with these module types will be processed.

`resolvedPaths` and `moduleTypes` are unioned, which means files match any of them will be processed.

Example:
```ts
import { UserConfig } from '@farmfe/core';
import farmJsPluginSass from '@farmfe/js-plugin-sass';

const config: UserConfig = {
  plugins: [
    farmJsPluginSass({
      filters: {
        // all files end with .custom-css will be processed
        resolvedPaths: ['\\.custom-sass$'],
        moduleTypes: ['sass']
      }
    })
  ]
}

export default config;
```

### implementation
`implementation` package name of `sass`. Default to `sass`. If you want to use `sass-embedded`, you can set it to `sass-embedded`.

```ts
import { UserConfig } from '@farmfe/core';
import farmJsPluginSass from '@farmfe/js-plugin-sass';

const config: UserConfig = {
  plugins: [
    farmJsPluginSass({
      implementation: 'sass-embedded'
    })
  ]
}
```
:::note
You should install `sass-embedded` manually.
:::

### additionalData
```ts
type AdditionalDataOption = string | ((content?: string, resolvePath?: string) => string | Promise<string>);
```
Additional data to be added to every sass file. Example:
```ts
import { UserConfig } from '@farmfe/core';
import farmJsPluginSass from '@farmfe/js-plugin-sass';

const config: UserConfig = {
  plugins: [
    farmJsPluginSass({
      // add variables.sass to every sass file
      additionalData: `
        @import "./src/styles/variables.scss";
      `
    })
  ]
}
```
For sass file:
```sass title="index.scss"
.foo {
  color: @primary-color;
}
```
`additionalData` will be added to the top of the file:
```sass title="index.scss"
@import "./src/styles/variables.scss";

.foo {
  color: @primary-color;
}
```

Function form:
```ts
import { UserConfig } from '@farmfe/core';
import farmJsPluginSass from '@farmfe/js-plugin-sass';

const config: UserConfig = {
  plugins: [
    farmJsPluginSass({
      // add variables.sass to every sass file
      additionalData: (content, resolvePath) => {
        if (resolvePath === '/path/to/index.sass') {
          return `
            @import "./src/styles/variables.sass";
          `;
        }
      }
    })
  ]
}
```

### globals
Global sass files. These files will be added to the top of every sass file. It's the same as `additionalData` but more convenient.

